Documentation on cgspec
Task: cgspec
Purpose: Overlay spectra on images with PGPLOT.
Categories: plotting
CGSPEC overlays spectra at spatial locations (specified in a text
file) on images (displayed via a colour pixel map representation
and/or contour plots) on a PGPLOT device.
Key: in
You may input up to 10 images. Some of these are used to make a
2-D spatial display (up to 3 displayed via contours and 1
displayed via a colour pixel map representation). Of the rest,
upto 5 may have spectra extracted from them, and 1 may be used
as a mask. The pixel map, contour, and mask images must be of
identical dimensions and size. Each spectrum image can be of any
dimensions, size, and order. The mask image blanking mask is
logically ORed to the pixel map and and contour plot image masks
before they are displayed. The mask image is not displayed.
These images can be input in any order (see TYPE).
Wild card expansion is supported. No default.
Key: type
Specifies the type of each image given, respectively, in the
IN keyword. Minimum match is supported (note that "pixel" was
formerly "grey" [which is still supported]). Choose from:
"contour" (contour; up to 3 of these) xyv
"pixel" (pixel map; up to 1 of these) xyv
"spectrum" (spectrum; up to 5 of these) any order
"dspectrum" (spectrum derivative ) any order
"mask" (mask; up to 1 of these) xyv
The "spectrum" images can be in any order. However, it will be
faster to have the spectrum on the first axis if the cube is
very large (i.e. the image should be in vxy order. Use REORDER
if necessary). The "dspectrum" images are the same as "spectrum"
images, except that the derivative of the spectrum with channel
is taken by CGSPEC before it is plotted. This is useful for
Zeeman enthusiasts. You can have up to 5 "spectrum" and
"dspectrum" images in total.
Key: region
Region of interest. This applies only to, and equally to,
the pixel map, contour and mask images. All the image planes
you select will be averaged before display. Only the bounding
box of the selected region is supported.
Key: xybin
Upto 4 values. These give the spatial increment and binning
size in pixels for the x and y axes to be applied to the selected
region. If the binning size is not unity, it must equal the
increment. For example, to bin up the image by 4 pixels in
the x direction and to pick out every third pixel in the y
direction, set XYBIN=4,4,3,1
Defaults are 1,XYBIN(1),XYBIN(1),XYBIN(3)
Key: slev
Up to 3 pairs of values for each contour image. First value is
the type of contour level scale factor; "p" for percentage and
"a" for absolute. Second value is the factor to scale LEVS by.
Thus, SLEV=p,1 would contour levels at LEVS * 1% of the image
peak intensity. Similarly, SLEV=a,1.4e-2 would contour levels
at LEVS * 1.4E-2
Default is no additional scaling of LEVS (i.e., "a",1.0)
Key: levs1
The levels to contour for the first specified contour image are
LEVS1 times SLEV (either percentage of the image peak or absolute).
Defaults try to choose something vaguely useful.
Key: levs2
LEVS for the second contour image.
Key: levs3
LEVS for the third contour image.
Key: grange
4 values. These are the image intensity range to display (min to max),
the transfer function type and the colour lookup table for the displayed
pixel map image. The transfer function type can be one of "lin" (linear)
"sqr" (square root), "log" (logarithmic), and "heq" (histogram
equalization). The colour lookup table is an integer from 1 to 8
specifying a lookup table. Valid values are 1 (b w), 2 (rainbow),
3 (linear pseudo colour), 4 (floating zero colour contours), 5 (fixed
zero colour contours), 6 (rgb), 7 (background), 8 (heat), and 9
(absolute b w). If you enter a negative integer, then the
reversed lookup table is displayed.
The transfer function changes available with OPTIONS=FIDDLE are in
addition (on top of) to the selections here, but the colour lookup
table selections will replace those selected here.
Default is linear between the image minimum and maximum with
a b w lookup table. You can default the intensity range with
zeros, viz. "range=0,0,log,-2" say.
Key: vrange
2 values. The velocity range, in km/s, to plot. If the first
axis of the spectrum image(s) is not velocity (say Frequency),
use the natural units of that axis.
Default is min to max from all the spectrum images.
Key: irange
2 values. The intensity range to plot for the spectra.
Default is min to max from all the spectrum images.
Key: iscale
Up to 5 values. A factor for each spectrum image by which it is
multiplied before plotting.
Defaults are all 1.
Key: spsize
2 values. These are the sizes of the spectra, in fractions
of the view-port, in the x- and y-directions.
Defaults are 0.1, 0.1
Key: stick
2 values. Major tick mark increments on the spectrum axes or
frame for labelling purposes.
No default.
Key: device
The PGPLOT plot device, such as plot.plt/ps
No default.
Key: labtyp
2 values; the spatial label types of the x and y axes.
Minimum match is active. Select from:
"hms" the label is in H M S.S (e.g. for RA)
"dms" the label is in D M S.S (e.g. for DEC)
"arcsec" the label is in arcsecond offsets
"arcmin" the label is in arcminute offsets
"absdeg" the label is in degrees
"reldeg" the label is in degree offsets
The above assume the pixel increment is in radians
"abspix" the label is in pixels
"relpix" the label is in pixel offsets
"absnat" the label is in natural coordinates as defined by
the header.
"relnat" the label is in offset natural coordinates
"none" no label and no numbers or ticks on the axis
All offsets are from the reference pixel of the contour/pixel map images
Defaults are "relpix", LABTYP(1) except if LABTYP(1)="hms" when
LABTYP(2) defaults to "dms" (to give RA and DEC)
Key: options
Task enrichment options. Minimum match of all keywords is active.
"blconly" means that if you have asked for some kind of spectrum
labelling (frame or axes), only draw the frame or axes for
the spectrum in the bottom left hand corner of the plot
"colour" means make the axes the same colour as the first
spectrum, else they are white.
"fiddle" means enter a routine to allow you to interactively change
the display lookup table. You can cycle through a variety of
colour lookup tables, as well as alter a linear transfer function
by the cursor location, or by selecting predefined transfer
functions (linear, square root, logarithmic, histogram equalization)
For hard copy devices (e.g. postscript), a keyboard driven
fiddle is offered; you can cycle through different colour tables
and invoke the predefined transfer functions, but the linear
fiddler is not available. In this way you can make colour
hardcopy plots.
"frame" means draw a frame to the left and bottom of each spectrum
and put the numeric labels on that frame. The default is no
frame plotting.
"full" means do full plot annotation with contour levels, pixel
map intensity range, image names, reference values, etc.
Otherwise more room for the plot is available.
"grid" means draw a coordinate grid on the plot rather than just ticks
"mark" marks the spatial location of the spectrum position with
a star. The spectra are plotted so that the centre if the
frame (which could be drawn with OPTIONS=FRAME) is at the
specified spatial location. This positioning is not very
obvious without the frame.
"mirror" causes all specified contour levels for all contour
images to be multiplied by -1 and added to the list of contours
"naked" means don't write the numeric axis labels on the spectrum
axes or frame so as to reduce clutter
"noaxes" means don't draw the X=0 and Y=0 axes which would,
by default, be drawn and have the numeric labels on them.
If the X=0 or Y=0 axes are not in the X and Y axis ranges of
your plot, then a FRAME (see above) option will automatically
be turned on for that axis.
"noblank" means draw the spectra where requested even if all of
the displayed 2-D images are blanked at that location. By
default, a spectrum is not displayed if all of the spatial
pixels over which the spectrum is averaged are blanked in all
of the displayed 2-D images. Otherwise you get to see it.
"noepoch" means don't write the Epoch into the spatial axis
label strings
"noerase" Don't erase a rectangle into which the "number"
string is written.
"normalize" This option makes each spectrum come out with a
peak of 1.0. This normalization is done after application
of ISCALE, so you could set ISCALE=-1 to make absorption
look like emssion and then normalize.
"number" writes the number of the spectrum in the corner of
the box surrounding the spectrum. The number is just
just the counter counting how many locations there are in
the overlay file (see OLAY).
"relax" means issue warnings when image axis descriptors are
inconsistent (e.g. different pixel increments) instead
of a fatal error. Applies to pixel map, contour and
mask images only.
"solneg1" means make negative contours solid and positive
contours dashed for the first contour image. The default,
and usual convention is the reverse.
"solneg2" SOLNEG1 for the second contour image.
"solneg3" SOLNEG1 for the third contour image.
"unequal" means draw plots with unequal scales in x and y
so that the plot surface is maximally filled. The default
is for equal scales in x and y.
"wedge" means that if you are making a pixel map display, also draw
and label a wedge to the right of the plot, showing the map
of intensity to colour
"1sided" means that for a derivative spectrum image, take a
1-sided derivative instead of the default 2-sided derivative
Key: clines
Up to 3 values. The line widths for each contour image
as specified in the order of TYPE. These widths are integer
multiples of 1.
Defaults are all 1 for interactive devices and 2 for
har copy devices.
Key: slines
Up to 5 pairs of values. These are the line widths and types
to use for the spectra for each spectrum image. Line types
can be 1 - 5 (solid and a variety of dashed/dotted types).
Widths are integer multiples of 1.
Defaults are all 1 for interactive devices, and 2,1 for
hard copy devices.
Key: blines
Up to 2 values. These are the line widths to use for 1) the border
and labels of the contour/pixel map display and 2) the border/axes
for the spectra. Widths are integer multiples of 1.
Defaults are 1,1 for interactive devices, and 2,2 for
hard copy devices.
Key: break
Up to 3 values. The intensity levels for the break between
solid and dashed contours for each contour image.
Defaults are 0.0,0.0,0.0
Key: csize
Up to two values. Character sizes in units of the PGPLOT default
(1, which is ~ 1/40 of the view surface height) for the
contour/pixel map labels and the spectrum labels.
Defaults try to do something useful.
Key: olay
You can either give one file name, or as many file names as there
are spectrum images. These files describe the locations at which
the overlay spectra are to be drawn. If you give one file only,
the locations described by it are applied to all the input spectrum
images. If you give several files, each of these corresponds
to the spectrum image in the order they are given in keyword IN.
Wild card expansion is active and there is no default.
Entries in the overlay file can be white space or comma
delimitered or both.
All lines beginning with # are ignored.
**** DO NOT USE TABS ****
Double quotes " are used below to indicate a string. The "
should not be put in the file. For all the string parameters
discussed below, you can abbreviate them with minimum match.
Miriad task "CGCURS" with OPTIONS=LOG,CGSPEC,CURSOR can be
used to prepare a file suitable as input to OLAY.
There are two formats, depending upon the first line.
----------------------
CASE 1; GRID LOCATIONS
----------------------
If the first line is
GRID
There should be one further line in the file:
XINC YINC XSIZ YSIZ
XINC and YINC are the increments across the contour/pixel map image
in ARCSEC at which spectra are to be drawn starting from the
bottom left corner of the display (defined by the REGION keyword)
XSIZ and YSIZ are the spatial half-sizes in ARCSEC over which
each spectrum is spatially averaged. These are optional and
default to 0 (no binning, just a spectrum at each spatial pixel)
---------------------------
CASE 2; IRREGULAR LOCATIONS
---------------------------
If the first line is
IRREGULAR
Each successive line describes one overlay spectrum location
according to:
XOTYPE YOTYPE X Y XSIZ YSIZ
XOTYPE and YOTYPE give the units of the overlay location
contained in the file for the x- and y-directions, respectively.
Choose from
"hms", "dms", "hms", "dms", "abspix", "relpix", "arcsec",
"arcmin", "absdeg", "reldeg", "absnat", and "relnat" as
described in the keyword LABTYP.
Note that %OTYPE does not depend upon what you specified for LABTYP.
X,Y defines the center of the overlay in the nominated OTYPE
coordinate system (X and Y OTYPE can be different). Note
that for coordinate systems other than "hms" and "dms", the
coordinates are with respect to the pixel map contour images
axis descriptors, not those from the spectrum images.
For %OTYPE = "abspix ", "relpix", "arcsec", "arcmin", "absnat",
"relnat", "absdeg", and "reldeg" X Y are single numbers.
For %OTYPE = "hms" or "dms", the X and/or Y location is/are replaced
by three numbers such as HH MM SS.S or DD MM SS.S. Thus if
XOTYPE=hms YOTYPE=dms then the file should have lines like
hms dms HH MM SS.S DD MM SS.S
XSIZ and YSIZ are the spatial half-sizes in ARCSEC over which
each spectrum is spatially averaged. These are optional and
default to 0 (no binning, just a spectrum at each spatial pixel)
Generated by rsault@atnf.csiro.au on 11 Jul 1996